[GOV-OBS-012] Внедрить структурированное JSON-логирование для ClickHouse

Перевод stdout шлюза на JSON Lines для интеграции с Vector и ClickHouse

Author

Services Task & Simulation Framework Documentation

Published

September 27, 2026

NoteКраткая карточка задачи
  • Репозиторий / Компонент: gov-registry-gateway (Go / SOAP Ingress).
  • Тип задачи: Инфраструктурная / Обсервабилити (Observability).
  • Справочник ошибок: [Раздел 5. Справочник ошибок технической документации]
  • Статус: Готово к реализации

  • Описание задачи:

    Для обеспечения сквозного мониторинга (Observability) работы сервиса Gov Registry Gateway, анализа качества интеграции и автоматического сбора аналитики в ClickHouse, необходимо перевести стандартный вывод логов (stdout) на структурированный формат JSON. Логи будут подхватываться агентом сбора логов (Vector/Fluentbit) прямо из контейнера, поэтому в коде не должно быть никакой текстовой примеси.

  • Инструкция по шагам:

    1. Удаление текстовых логов: Полностью удалить из кодовой базы стандартные вызовы log.Println и log.Fatalf после инициализации БД. Логирование в os.Stdout должно содержать строго одну валидную JSON-строку на одно событие (формат JSON Lines).
    2. Подключение логгера: Интегрировать структурированный логгер (рекомендуется встроенный slog из Go 1.21+ или uber-go/zap). Текстовые примеси в потоке вывода запрещены, так как они ломают сборщик логов Vector.
    3. Формирование базовых полей: Настроить автоматическую генерацию полей для каждого события: timestamp (в формате RFC3339 Nano), level (INFO, WARN, ERROR, FATAL) и ui_payload (для данного сервиса всегда передавать null).
    4. Реализация логирования бизнес-ошибок (На Шаге 7 и Шаге 13): При возникновении нештатных ситуаций или отказов авторизации, формировать корневое поле canonical_code и вложенный объект observability_json в точном соответствии со справочником ошибок:
      • При невалидном/отозванном токене: canonical_code: "GOV_AUTH_DENIED", в transport_statuses передавать {"grpc": 16, "http": 401}, а в observability_json.labels указывать причину token_invalid_or_revoked.
      • При отсутствии записи в реестре: canonical_code: "DB_EMPLOYEE_NOT_FOUND", в transport_statuses передавать {"grpc": 5, "http": 200}, а в метрику отправлять ярлык user_id_absent.
    5. Логирование критических сбоев СУБД: В блоке обработки системных ошибок соединения с PostgreSQL формировать лог с уровнем FATAL, кодом DB_GOV_POSTGRES_DOWN, статусами {"grpc": 14, "http": 500} и таргетом INTERNAL_SYSTEM. Внутри меток ClickHouse передавать точное имя базы данных gov_registry_db.
    6. Логирование успешных запросов (На Шаге 15): При успешной отдаче персональных данных сотрудника формировать лог со значением canonical_code: "SUCCESS", уровнем INFO и статусами {"grpc": null, "http": 200}.